(1) Field of the Invention
This invention relates generally to a method and apparatus for generating documentation and more specifically to a method and apparatus for facilitating the development of documents representing specifications of external interfaces.
(2) Description of the Prior Art
The documentation of interface specifications involves a process for providing detailed specifications and control drawings that define an external interface between different "systems" comprising hardware, software or a combination thereof. The decisions involved in formulating such specifications generally require a great deal of interaction between the personnel who develop the software and/or hardware portions of such system. These resulting documents often serve as an aid to the development personnel of the respective software and hardware portions of the system in their efforts to provide respective software and hardware portions that successfully operate with each other and with the external systems through external interfaces. Prospective purchasers and users frequently rely on these documents to determine whether a particular system is appropriate and/or is being developed appropriately.
Documenting the specifications of external interfaces generally commences and continues as an iterative process involving the individuals and groups working on the respective portions of the software/hardware system being designed. The documentation thus frequently specifies an external interface for a software/hardware system not fully developed and tested. Therefore the specifications reflected in such documents frequently require updating, modifying and revising to reflect various design and developmental changes and refinements. Additionally, changes in the external components connecting through the external interface may also change; this can also require changes to the equipment under development. Consequently, the detailed specifications and control drawing documentation contained within the specification documentation often change over time. Assuring that all portions of the documentation reflect a specific change is a tedious and difficult task.
The foregoing methods for generating the documentation of an external interface specification thus often result in typographical errors and in miscommunication and misunderstanding between the development personnel. These errors can result in inoperative or partially inoperative external interfaces because the hardware/software systems were designed to meet the erroneous documentation. In other situations the documentation may fail to reflect the actual specifications of the external interface.
To reduce these errors, generally a person or group is assigned as having approval authority for making "final" approval decisions. This discipline tends to reduce the instances of errors due to miscommunication between developers of the system portions. However, errors of this type still occur too frequently. Further, the amount of time spent in preparing and revising documents to eliminate these errors and in meetings to discuss erroneous specifications reflected by such documents continues to absorb much valuable time. The use of an approval authority also has not greatly reduced the instances of clerical or typographical errors. In fact, portions of such documentation often are not internally consistent leading to further errors and mistakes. Thus, even with such controls, development personnel can still spend an inordinate time in meetings, arranging meetings and preparing for such meetings to develop the documentation and to resolve or reduce errors in the previously generated documentation.
In recent years some attempts have been made to automate documentation, and the following U.S. Letters Pat. Nos. disclose some of these efforts:
5,043,891 (1991) Goldstein et al. PA1 5,038,316 (1991) Hempleman et al. PA1 5,063,534 (1991) Kishimoto PA1 5,079,701 (1992) Kuga et al.
U.S. Letters Pat. No. 5,043,891 to Goldstein et al. discloses a documentation generation system that uses a definition-based expert system and an editor to produce an output document from a template document and expert system. The knowledge base of the expert system includes a database comprising a hierarchy of a plurality of terms and their respective definitions. An inference engine component of the expert system evaluates a term by evaluating all the definitions for the terms which are generally in the hierarchy of definitions. The terms include fragment text that are defined as portions of the template system. The editor inserts the fragment text portions into the template document in place of the particular fragment names to produce a generated document comprising the fragment text and textural portions of the template document.
U.S. Letters Pat. No. 5,038,316 to Hempleman et al. discloses a software system for automatically generating end user documentation that includes the steps of providing a file of tables defining the software system. Another step in the method involves providing a file of text and commands, defines the desired documentation and a documentation output file. Each entry of a text and command file is examined to determine whether the entry is a command. A command is executed and any requested output is generated. At least some of the generated output is stored in the output file. Text entries are also stored in the output file.
To a certain extent, the process of generating documentation broadly incorporates concepts useful in translation. The following U.S. Letters Pat. Nos. disclose various electronic translating and dictionary units:
U.S. Letters Pat. No. 5,063,534 to Kishimoto discloses an electronic translating unit for inputting words of a first or second language. A first memory section stores words of the first language and addresses of sentences associated with the words. A second memory section stores words of the second language and addresses of second sentences associated with the words. A third memory section establishes correspondences between sentences of the first and second languages corresponding to the words. An access control device responds to the input of a word of one of the languages accesses both corresponding words of the other language and addresses for sentences in either of the languages corresponding to the input and accessed words. The device also enables display of the sentences by user manipulation.
U.S. Letters Pat. No. 5,079,701 to Kuga et al. discloses a word processing computer for entering and storing Japanese symbols and character strings. A memory portion of the computer includes an operator defined dictionary. To enter new words into the dictionary the computer displays reference words similar in linguistic form to the new words and parts of speech which are prestored in the dictionary. The operator can then compare the reference words with the new words and thus identify parts of speech in proper form for entry into the defined dictionary.
A Computer Aided System Engineering (CASE) tool also enables the automation of the generation of software specification documentation for developing and maintenance, and use of the software systems. For example, META Systems, Ltd. of Ann Arbor, Mich. has developed a CASE tool for the United States Department of Defense that generates DoD-STD-2167 standard documents for software systems and their internal interfaces. The CASE tool operates by analyzing a software system and generating a specification of various parameters of the software. However, such CASE tools do not provide information for a comprehensive documentation of an external software/hardware system during the development of such systems. That is, CASE tools do not enable automatic generation of the specifications of an external interface of a software/hardware system.
Notwithstanding these efforts, the prior art fails to define any system for facilitating the development of requirements for external interfaces of a software/hardware system. Thus generating, updating, and maintaining of an external interface specification documents such as the type specified by DoD-STD-2167A, continues to require significant manual efforts by various groups. Errors in the documentation still occur and continue not to be recognized. Consequently often times portions of the software and hardware under development fail to operate in an intended manner. Additional corrective design effort and work continues to be necessary that could be otherwise avoided by reducing these errors. Moreover, errors left uncorrected can also lead to mistakes and faulty decisions by users and potential users. Nothing in the prior art discloses any method and apparatus that facilitates the defining of an interface definition for external interfaces in software/hardware systems characterized by ease of use and by inhibiting errors from developing in the specification, particularly a method or apparatus for automatically generating documents representing the definition of the external interface.